home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 2: CDPD 1
/
Almathera Ten on Ten - Disc 2: CDPD 1.iso
/
pd
/
276-300
/
297
/
devkit
/
devkit.doc
< prev
next >
Wrap
Text File
|
1995-03-14
|
45KB
|
935 lines
DevKit - Release 1.2 - August 29, 1989
DevKit files and programs copyright (c) 1989, Peter Cherna. See below
for distribution restrictions.
Contents
1.0 Introduction
1.1 Copyright and Distribution Notices
1.2 Disclaimers
1.3 Contents of the DevKit
1.4 Considerations for Use
2.0 ARexx Scripts
2.1.1 Compile.ced
2.1.2 Compile.WShell.ced
2.2 NextError.ced
2.3 LookUp.ced
2.4 LookUpHeader.ced
2.5 LookUpTag.ced
2.6 BlockSearch.ced
2.7 SetScriptBit.ced
2.8 CommentBlock.ced
2.9 UncommentBlock.ced
2.10 ARexx Notes
2.11 CygnusEd Notes
3.0 Shell/CLI Scripts and Other S Directory Stuff
3.1 SetSource
3.2 MakeTags
3.3 RexxCommands
4.0 Executable Programs
4.1 WBTF
4.2 GetAutoDoc
4.3 MakeAutoDocIndex
4.4 MakeHeaderIndex
4.5 GenTags
5.0 C Language Sources
6.0 Conclusion
7.0 Future Avenues
1.0 Introduction
What is the DevKit? The DevKit is a collection of C and ARexx
language programs to facilitate the life of the software developer.
With the DevKit, you can launch your compiler from within your editor,
have the cursor positioned on your errors, look up the autodoc page
for any Amiga function at a single keystroke, find a system structure
or #define within the include files, or find any function in the
source code you are developing. As well, it provides a utility where
you can put the compiler options in the source code for easy reference
and modification.
The compiling and error-finding functions are designed to work with
CygnusEd Professional and Manx C 3.6a. You also gain a slight
advantage if you own WShell. A dedicated worker could adapt these to
other compilers or ARexx-compatible editors. The autodoc lookup works
from the CLI as well, and is useful to anyone possessing the 1.3
Native Developer's Kit from Commodore, containing the autodoc and
include files.
1.1 Copyright and Distribution Notices
The files and programs that make up the DevKit are Copyright (c) 1989,
Peter Cherna, and are freely redistributable with the following
conditions:
1. All the files and programs that make up the DevKit shall be
kept together in unmodified form.
2. Any modified files may be added to the DevKit provided they
are in a separate directory for modified files, and clearly
marked as being modified (by whom, when, and for what
purpose). The original unmodified files must still remain
as they were in the DevKit. Any such modified files must
have no further restrictions on distribution than those
restrictions given here for the DevKit.
3. The DevKit may be not be distributed for profit. Only a
nominal charge may be associated with its distribution.
4. The DevKit may not be distributed along with any commercial
product without prior consent from the author of the DevKit.
1.2 Disclaimers
The DevKit is provided as is, without warranty of any kind. You
assume full risk of its use. So there, but don't let that scare
you.
I am in no way affiliated with Manx, William Hawes, or
ASDG/CygnusSoft, other than being a happy user of their products.
The DevKit works with products from these developers because
those products were appropriate for the need at hand.
The DevKit software and documentation is my own and in no way
expresses any opinions of, recommendations of, or guarantees on
the part of my employer.
1.3 Contents of the DevKit
DevKit.doc This documentation file.
Rexx (dir) Directory containing ARexx scripts for
CygnusEd Professional.
Compile.ced Launch compiler from within editor.
Compile.WShell.ced Launch compiler from within editor, for
WShell users.
NextError.ced Find next Aztec C error.
LookUp.ced Look up a system function in the
autodocs.
LookUpHeader.ced Look up a #define'd constant or
structure in the header files.
LookUpTag.ced Look up a function within your source
code.
BlockSearch.ced Search for marked region.
SetScriptBit.ced Sets the script bit of the current file.
CommentBlock.ced Comments out the marked section of code.
Handles the fact that in C, comments do
not nest.
UncommentBlock.ced Uncomments a block that was commented
out using CommentBlock.ced.
s (dir)
SetSource Shell/CLI script that allows you to use
an environment variable to specify your
source directory.
MakeTags Generates tags from multiple source
files, for later use by LookUpTag.ced.
RexxCommands Configuration file for CygnusEd
Professional that binds the DevKit ARexx
functions to function keys.
c (dir)
GetAutoDoc Extracts an autodoc for the specified
function.
MakeAutoDocIndex Builds the index files for the autodocs.
MakeHeaderIndex Builds the index files for the compiler
headers.
WBTF Utility that brings the Workbench to the
front.
GenTags Generate tags for a single source file.
Sources (dir) Source code for the above modules.
GetAutoDoc.c
MakeAutoDocIndex.c
MakeHeaderIndex.c
WBTF.c
GenTags.c
Examples (dir)
AutoCommands Some "Auto:" commands to illustrate the
use of Compile.ced.
1.4 Considerations for Use
The DevKit was designed for relatively well-equipped Amigas, i.e. hard
disks and extra memory. There is no reason why it shouldn't work on a
1 Meg floppy-based system, but it may be difficult to have CygnusEd,
ARexx, and the Aztec C compiler all running in 512K. The lookup
functions depend on having the autodocs or compiler headers plus some
special index files available. The AutoDocs take about 710K, plus
about 55K for the index files. The compiler headers take about 435K,
plus about 100K for the index files. For convenience, it is desirable
that they be kept on a hard disk, but they will work quite well (and
reasonably fast) if kept on a floppy disk.
2.0 ARexx Scripts
Nine ARexx scripts can be found in the Rexx directory of the DevKit.
These scripts are designed to work from CygnusEd Professional, a high-
performance editor available from ASDG Inc. Several of the scripts
work in conjunction with the Aztec C compiler from Manx Systems.
These scripts are designed to take advantage of ARexx version 1.10.
If you have an earlier version, you should definitely upgrade to the
latest version, at least 1.10.
2.1.1 Compile.ced
Compile.ced is an ARexx program designed to work with CygnusEd
Professional. It is used to launch a compiler (usually to compile the
file that you are currently editing). It could easily be adapted to
other programs that depend on a text file for input.
In the file you are editing, you must place a comment that tells
Compile.ced what to do with your file. You want to provide
Compile.ced with a series of commands to perform, typically compiling
and linking your file. Near the beginning of your source code, for
each command that is to be executed by Compile.ced you must include
the word "Auto:" followed by the desired command. The command may
include the special wildcards <path> and <file>, which stand for the
path to your file and the file name (less its extension, usually
".c"). To illustrate, if your file was "DH0:Sources/MyStuff.c", and
you wished to compile and link it under Aztec C (with standard
options, and sending the .o file to the RAM: disk), you would put the
following in a comment near the beginning of your code.
Auto: cc -o ram:<file>.o <path><file>
Auto: ln ram:<file>.o -lc -o <path><file>
Compile.ced will find these commands, substitute the string
"DH0:Sources/" for each occurrence of the string <path> and substitute
the string "MyStuff" for each occurrence of the string <file>, and
will execute the resulting commands:
cc -o ram:MyStuff.o DH0:Sources/MyStuff
ln ram:MyStuff.o -lc -o DH0:Sources/MyStuff
Compile.ced expects to find the first occurrence of "Auto:" within the
first thirty lines of your source code, and will continue processing
until a line without an "Auto:" is found. This means that all the
"Auto:" commands must be on consecutive lines (no skipping allowed).
You must use "Auto:" as written because case matters, so don't use
"AUTO:" or "auto:".
(You probably will want to make use of Compile.ced and NextError.ced's
ability to tell you where the errors your compiler found are. To do
so, you should use option -q of Aztec's cc compiler, which sends error
messages (but not warnings) to a file called "AztecC.err" in the
current directory.)
If you install Compile.ced on a CygnusEd function key (say F1) by
setting its command to be "run rx Compile.ced", you will be able to
continue editing another file during compilation. When you press F1,
Compile.ced checks to see if the file has been modified since the last
save, and asks you if you wish to save before compiling. Select "Yes"
to save, or "No Way!" to compile without saving. Once the Workbench
screen pops up, and Compile.ced announces that it is scanning your
file, you are free to continue editing this or other files.
Compile.ced then looks for "Auto:" commands in your file. If none are
found, you will be informed of the problem. Otherwise, Compile.ced
executes performs the substitutions for <path> and <file>, and then
executes the "Auto:" command.
If the compiler failed because there were errors in your source, then
Compile.ced will recognize that (by looking for the file AztecC.err).
It will invoke the ARexx program NextError.ced (see below), which will
locate and display the errors the compiler found in your source.
If there are no compilation errors, you will be told so, and you then
have the choice of returning to the Workbench screen (to test your
code) or staying with the editor.
Unfortunately, Compile.ced has no way of catching "Auto:" commands
that fail, other than when Aztec's compiler detects errors and creates
the AztecC.err file. As a result, being told that there were no
compiler errors doesn't guarantee that the linker didn't fail, for
example. If you use WShell, this problem can be overcome by using the
Compile.WShell.ced ARexx script in place.
The advantages of having "Auto:" commands are obvious. The
instructions on how to compile a program remain with the program's
source itself. If you decide to change a compiler option, you just
modify the "Auto:" line in your source (if you want debugging
information for Aztec SDB, just add option -n to the compiler line,
and -g to the linker line, press F1, and voila!) If you need to link
with the math library, you say so right in your source code. Because
of the substitution for <path> and <file>, you can safely move your
source code to a new directory and it will compile from there as well.
Compile.ced does not provide any dependency analysis in the style of
make. Of course, nothing stops you from using make as your "Auto:"
command, as in
Auto: make <file>
Note that any DOS command is ok as an "Auto:" command.
All the files in the Sources directory of the DevKit were compiled via
Compile.ced. You can look at how those files are set up to get some
ideas on how to proceed. For some other example "Auto:" commands, see
the file AutoCommands in the Examples directory of the DevKit.
2.1.2 Compile.WShell.ced
Compile.WShell.ced is an ARexx program that is very similar to
Compile.ced described above. It does everything that Compile.ced does
but takes advantage of an extra feature currently offered only by
WShell, which allows an ARexx program to tell the success or failure
of a DOS command it executed. This includes the "Auto:" commands. If
you own WShell, you should use this ARexx program in place of
Compile.ced. Compile.WShell.ced will inform you of exactly which
"Auto:" command failed, and will stop processing further "Auto:"
commands. This is useful if, for example, you pressed control-C
during compiling, or if the linker failed to resolve all references.
2.2 NextError.ced
NextError.ced is an ARexx program designed to work with CygnusEd
Professional and Aztec C which takes the AztecC.err error file
generated by the Aztec compiler and locates the errors within your
source. The cursor of the editor will be placed on the error, and a
requester will appear giving the error message.
If you install NextError.ced on the F2 function key in CygnusEd, you
can always get the next error by pressing F2. Compile.ced launches
NextError.ced when it detects compiler errors, so your errors appear
automatically after compiling.
NextError.ced finds out which source file contains the next error (it
could be in something you've #include'd.) If you don't have that file
currently displayed in CygnusEd, you will be told that there is an
error in that file and what the error is, and then you will be asked
if you want it loaded into CygnusEd. If you say yes, it will be
brought in. If you say no, then that error will be skipped. If the
file with the error is already displayed in CygnusEd (or has just been
brought in at your request), then the cursor will be moved onto the
error, and a requester will appear giving the name of the file, the
line in the source, the error number, and the error message. You will
be asked if you wish to go to the next error or not. If you say yes,
then the next error will be found. If you say no, you will be able to
edit. Later, you can get the next error by calling NextError.ced
(press F2).
When there are no more errors, NextError.ced will tell you so. If you
then call NextError.ced again, the first error will be redisplayed,
and on from there.
When NextError.ced tries to place the cursor on your error, there are
a few things that must be remembered. First, the compiler is only so
good at figuring out where the error really is. A missing semicolon,
for example, is usually flagged at the beginning of the next line.
Second, if you have changed your file since you compiled it (say by
fixing an earlier error), and this has meant changing the number of
lines before the error, then the cursor will miss the error by that
number of lines. Likewise, if you've modified the line that contains
the error, the cursor may miss the error by a number of characters.
Finally, and this is important, NextError.ced can account for tab
characters only under certain conditions. You must be using a fixed
tab size (any tab size is ok) and not custom tabs. Second, all the
tabs had better be at the beginning of the line. If your line has
embedded tabs, such as
foo(...);<TAB>bar(...);
and the compiler finds fault with the parameters of bar(),
NextError.ced will land the cursor slightly over from where it should
be. More insidious is a line with a hidden space, say
<SPACE><TAB>foo(...);
which looks exactly like
<TAB>foo();
The line with the hidden space will cause NextError.ced to misplace
the cursor a bit.
2.3 LookUp.ced
This is an ARexx program designed to work with CygnusEd Professional.
The word under your cursor (or immediately to the left of your cursor)
will be taken as the name of the Amiga system function you wish to
look up in the autodocs. This is done by invoking the program
GetAutoDoc (see later discussion for its stand-alone use). Note that
you must have assigned the label "AutoDocs:" to the directory
containing your autodoc files (or placed your autodoc files on a disk
called "AutoDocs"), and you must have run MakeAutoDocIndex to build
the indexes that GetAutoDoc needs to find autodoc entries efficiently.
LookUp.ced identifies the word in your text by looking for all
adjoining alphanumeric characters (as well as the underscore symbol
"_"). If CygnusEd's cursor is on a character in a word or on the
character immediately after the word (i.e. it's ok if your cursor is
on the open bracket following the function), LookUp.ced will attempt
to find a function by that name in the autodocs. If your cursor is
not on a word, a string requester will appear, into which you may type
the name of the function to look up. If no autodoc is found for the
word you desire, you will be told.
When an autodoc is found, LookUp.ced will open a new view in CygnusEd
and put the autodoc for the requested function in that view. If you
already have a view in CygnusEd that was opened by LookUp.ced or
LookUpHeader.ced (see below), and its contents haven't been modified,
then LookUp.ced (like LookUpHeader.ced) will use this view rather than
opening yet another one. This helps prevent excessive clutter of the
CygnusEd window/screen.
Like NextError.ced (above), and LookUpHeader.ced (below), Lookup.ced
can get a bit lost if you are using custom tabs, or if you have
embedded tabs. Tabs of any fixed size, so long as they are at the
beginning of the line, are ok.
2.4 LookUpHeader.ced
Similar to LookUp.ced, LookUpHeader.ced is an ARexx program designed
to work with CygnusEd Professional and the compiler headers files.
The word under your cursor (or immediately to the left of your cursor)
will be taken as the name of the Amiga system structure or #define'd
constant that you wish to look up in the compiler headers. If your
cursor is not on a word, a string requester will appear, into which
you can type the name of the structure or constant you want to look
up. Note that you must have assigned "ch:" to the directory
containing your compiler headers (or placed your compiler headers on a
disk named "ch"), and you must have run MakeHeaderIndex to build the
indexes that LookUpHeader.ced needs to find system structures and
constants efficiently.
If the system structure or constant is found, LookUpHeader.ced will
load the appropriate compiler header file into CygnusEd and place the
cursor on the appropriate line. As explained in the discussion of
LookUp.ced, LookUpHeader.ced will (if it can) use a view in CygnusEd
that was previously opened by LookUp.ced or LookUpHeader.ced.
2.5 LookUpTag.ced
LookUpTag.ced is an ARexx program designed to work with CygnusEd
Professional and your own source code, be it in one or more modules.
The word under your cursor (or immediately to the left of your cursor)
will be taken as the name of the function that you wish to look up in
your source files. If your cursor is not on a word, a string
requester will appear, into which you can type the name of the
function you want to look up. LookUpTag.ced will make use of the tags
file that you must have previously generated by using MakeTags or
GenTags (see below). LookUpTag.ced assumes that this tags file may be
found in the same directory as the file in the current window of
CygnusEd.
If the requested function is found in the tags file, LookUpTag.ced
will load the appropriate source module into CygnusEd if it is not
already loaded (or make use of an already-loaded copy) and place the
cursor on the appropriate line.
2.6 BlockSearch.ced
This is a little freebie (an extra included at no charge in a free
package?!?) which allows you to highlight a block of text in CygnusEd
(don't cut it or copy it, though), and turn it into the object of a
search. (The search will be a forward one, with the current settings
of case sensitivity, words only, and wildcards.) If you want to
search backwards, you can 'Repeat Search Backwards' (AMIGA-a)
afterwards. It sure beats retyping something into the search
requester. You may install this ARexx program directly on a function
key. Note that only the first word in the block will be taken, so if
you highlight the words "foo bar", and invoke BlockSearch.ced, the
object of the search will be "foo".
2.7 SetScriptBit.ced
Another freebie (see above :->) which sets the script bit of the
current file in CygnusEd. When I edit my script files and re-save
them, I lose the script bit. If you install this ARexx program on a
CygnusEd function key, you can fix the script bit with a single
keystroke.
2.8 CommentBlock.ced
An unfortunate feature of the C programming language is that comments
do not nest (although some compilers allow nested comments as an
option). Sometimes, it is convenient to comment out a whole section
of code, but a problem arises if this section itself contains
comments. CommentBlock.ced is an ARexx program that takes the
currently highlighted block in CygnusEd, encloses it in comments, and
replaces the comment brackets within the block ('/*' and '*/') with
false brackets that the compiler will ignore ('<*' and '*>'). Thus,
it becomes possible to comment a whole block of code, as if comments
did nest. If you apply CommentBlock.ced to a block that already
contains some false brackets from a previous invocation, the false
brackets will grow (i.e. '<*' becomes '<<*', etc.) so that you may
successfully comment out something that already is.
2.9 UncommentBlock.ced
UncommentBlock.ced is the matching inverse function to
CommentBlock.ced. It takes the currently highlighted block in
CygnusEd, and begins by removing the first open comment sequence
('/*') and the last close comment sequence ('*/'). (It is not a
problem if either an open or close comment is not found). It then
replaces all the false comment brackets ('<*' and '*>') within the
block with true comment brackets ('/*' and '*/'), or it shrinks them
(i.e. '<<*' becoms '<*', etc.). It effectively uncomments a block
that was commented out with CommentBlock.ced (described above).
2.10 ARexx Notes
These ARexx programs are relatively robust examples of driving
CygnusEd and DOS commands from within an ARexx program.
Of course, to run ARexx programs from within CygnusEd, you must run it
with the -keepio option, as in
run ced -keepio
One possible area of difficulty is in executing DOS commands from
within an ARexx program. The ARexx command "ADDRESS COMMAND cmd"
executes the program specified by 'cmd'. If you don't include the
full path to the file, then your path is searched. As explained in
the ARexx 1.10 documentation, the path will be that in effect when
CygnusEd was run. The DOS programs called by these ARexx programs
(DevKit programs GetAutoDoc and WBTF, and DOS commands delete and
search) must be in one of the directories in your path, or in the C:
directory. This is also true of any program called by an "Auto:"
command without a full path specification, meaning cc, as, and ln.
You may of course give a full path specification in your "Auto:"
commands, by doing something such as
Auto: Aztec:ln ...
However, take note that even if you give the full path to the
compiler, Aztec expects the assembler to be in the current directory
or anywhere in the path.
The only way for an ARexx program to find which view in CygnusEd
Professional contains a particular file is to go to each successive
view until the correct one is found. If you use CygnusEd's "Auto-
expand views" option (which makes the current view expand to the
largest possible size), then there will be a certain amount of
flashing as NextError.ced, LookUp.ced, and LookUpHeader.ced attempt to
locate the correct view. If you can't do without "Auto-expand views",
you will have to put up with the flashing, at least until a few more
functions are added to the ARexx interface of CygnusEd Professional.
An important point to note is that Aztec's cc compiler places its
error file AztecC.err in the current directory, which will be the
current directory at the time CygnusEd Professional was run. If your
current directory is write-protected, cc won't be able to open the
error file. CygnusEd has a menu option that lets you change its
current directory. You may also add a line to Compile.ced such as
call pragma 'Directory', "RAM:"
which will change the current directory of the ARexx script to RAM:.
Another straightforward solution is to use a file zapper on the Aztec
compiler cc and change the string 'AztecC.err' and to something like
'RAM:Az.err' (note that it has to be exactly the same length, i.e. 10
characters). Use a text editor to make similar changes in Compile.ced
and NextError.ced, and Aztec's error messages will always go to the
RAM: disk.
2.11 CygnusEd Notes
The ARexx programs in the DevKit make extensive use of the CygnusEd
ARexx interface. Almost anything the user can make CygnusEd
Professional do can be done over the ARexx port. For those interested
in adapting the DevKit to other text editors, here is a brief
description of the CygnusEd ARexx functions that are used in the ARexx
programs of the DevKit. CygnusEd always returns the result of a
function in the variable named "result".
address 'rexx_ced': Informs the ARexx server of the desire to
communicate with CygnusEd.
cedtofront: "cedtofront" brings the CygnusEd window to the
front and activates it.
copy block: "copy block" puts a copy of the currently
highlighted block into the block buffer, and
unhighlights it. If the operation was successful,
the return value "result" will be uninitialized
(i.e. equal to the string "RESULT"), otherwise it
will contain an error message (such as "No block
marked").
cut block: "cut block" behaves just like "copy block" except
that the currently highlighted block is also
removed from the file.
getstring: "getstring" asks CygnusEd to put up a requester,
into which you may type a string, which will be
returned in the variable "result".
jumpto: "jumpto line char" moves the cursor to the
specified line and character (the first line of
the file and the leftmost character are taken as
1).
menu: "menu menu item sub" executes the function at the
specified menu, menu item, and sub item (count
from zero up). "menu 2 1 7" is used to set the
tab size to eight.
next view: CygnusEd supports multiple views (like having
multiple windows, with the same or different file
in each window). "next view" moves the cursor
into the next view.
okay1: "okay1 text" causes CygnusEd to present a
requester containing the specified text with a
single gadget ("Resume?").
okay2: "okay2 text" causes CygnusEd to present a
requester containing the specified text with two
gadgets ("Yes" and "No Way!"). A result of 1
indicates that the "Yes" gadget was selected,
while a result of 0 indicates that the "No Way!"
gadget was chosen.
open: "open file" causes CygnusEd to load the specified
file into the current view.
open new: "open new" causes CygnusEd to create a new (empty)
view by splitting the current one.
search for: "search for string" causes CygnusEd to initiate a
forward search for the specified string. If the
search was successful, the return value "result"
will be uninitialized (i.e. equal to the string
"RESULT"), otherwise it will contain an error
message (such as "'string' not found")
text: "text string" will cause the supplied string to be
entered at the current cursor position.
CygnusEd also provides the "status n" command which, depending on the
value of n, returns a value or string known to the editor. The
variable "result" contains the answer. The ones used in the DevKit
are:
8: "status 8" returns the tab size.
18: "status 18" returns the number of changes to the file in the
current view since the last time it was saved.
19: "status 19" returns the full path and file name of the file
in the current view, eg. "Workbench:Sources/MyStuff.c"
20: "status 20" returns the path of the file in the current
view, eg. "Workbench:Sources"
21: "status 21" returns the name of the file in the current view
(without the path), eg. "MyStuff.c"
46: "status 46" returns the x position of the cursor (the first
column is taken as 0).
47: "status 47" returns the y position of the cursor (the first
line of the file is taken as 0).
55: "status 55" returns a string which is the text on the
current line (tabs are not converted to spaces.)
60: "status 60" returns a string which is the contents of the
block buffer.
66: "status 66" returns the number of views currently open in
CygnusEd.
3.0 Shell/CLI Scripts and Other S Directory Stuff
The DevKit includes a Shell script.
3.1 SetSource
SetSource is based on a script I use. If I want to work on some c
files that are in a particular directory of my disk, say "cc:Tools", I
type at the Shell prompt:
SetEnv Source cc:Tools
As my ENV: directory is on my hard disk (and not in RAM:), this
environment variable survives reboots and power-offs. When turn on
the computer to resume developing or when I reset the computer after a
crash, the script SetSource will get this environment variable and
assign the logical label src: to it. I also invoke CygnusEd with a
file name (or more accurately a directory name) of src:, so that when
I want to open a file, the directory is set to my source directory.
Scripts like SetSource that stuff parameters into commands look a bit
ugly, but can be very effective.
3.2 MakeTags
MakeTags is a shell script that allows GenTags to be run for multiple
source files, with the result being stored in a file called tags in
the current directory. Its syntax is
MakeTags [pat]
where pat is an optional pattern (defaulting to #?.c, or all .c
files). So if you wanted to make tags for all .c files beginning with
a w, you would use
MakeTags w#?.c
MakeTags displays the name of each file as it is scanned.
Normally you will use MakeTags, and not call GenTags directly.
3.3 RexxCommands
RexxCommands is a file generated and used by CygnusEd Professional
(and placed in the S directory) which specifies the ARexx or DOS
commands that are attached to each function key. RexxCommands makes
the following bindings for the ARexx scripts of the DevKit:
F1 run rx Compile.ced
F2 NextError
F3 CommentBlock
F4 UncommentBlock
F6 SetScriptBit
F7 BlockSearch
F8 LookUpTags
F9 LookUpHeader
F10 LookUp
4.0 Executable Programs
The DevKit contains five executable programs in the C directory that
are needed to run the ARexx scripts in the DevKit.
4.1 WBTF
WBTF is the simplest one, and it just brings the Workbench screen to
the front, so that you may see what the compiler, or whatever is
doing. It has no arguments. (CygnusEd is brought to the front
through the ARexx command "cedtofront" that it provides.)
4.2 GetAutoDoc
GetAutoDoc extracts the autodoc for a function. You must have the
autodocs available in a directory, and have assigned the label
"AutoDocs:" to that directory. Also, you must have run
MakeAutoDocIndex to build the indexes that GetAutoDoc needs to quickly
extract the autodoc for a function.
To use GetAutoDoc, just type
GetAutoDoc function
Where function is the name of the Amiga system function you would like
the autodoc for (you may use upper, lower, or mixed case - it doesn't
matter). If the function is found, the autodoc page will be sent to
the screen. You may of course redirect the output to a file (that's
what LookUp.ced does.) If the function is not found in the autodocs,
or some other error occurs, you will be told.
If you just type
GetAutoDoc
You will get a brief summary of usage.
GetAutoDoc returns an error code of 20 if a critical error occurred,
an error code of 5 if no autodoc for the desired function was found,
and an error code of 1 if the summary of usage was displayed. The
error code of zero is reserved for successfully finding an autodoc.
Furthermore, all error strings are guaranteed to begin with a dash
followed by a space, as in
- Foo not found.
4.3 MakeAutoDocIndex
MakeAutoDocIndex is a program that builds index files from the
autodocs so that GetAutoDoc may work efficiently. It assumes that the
autodocs are the ones from the 1.3 Native Developer's Kit, available
from Commodore. It scans all the files in the "AutoDocs:" directory
that end in ".doc". These had better be genuine autodoc files. A
genuine autodoc file contains:
A list of the functions (or whatever, MakeAutoDocIndex doesn't
care)
Form Feed
A set of {
Autodocs for one function
Form Feed
}
Assuming that nothing goes wrong, MakeAutoDocIndex will create a bunch
of files in a subdirectory called "Index" that it creates in the
"AutoDocs:" directory. These files are called IndexA, IndexB, etc.
Each file contains all the functions that start with that letter or
symbol (there will be an Index_ file). The format will be:
function; library; autodocfile offset
where function is the name of the function (eg. OpenScreen), library
is the system library it belongs to (eg. intuition.library),
autodocfile is the full name of the autodoc file (eg.
AutoDocs:LibrariesA-K/intuition.doc) and offset is the byte offset
into the autodoc file where this function begins (eg. 68810).
Some sharable libraries include an autodoc-type file. You may easily
modify the source to MakeAutoDocIndex and recompile if you wish to
index these as well. To modify MakeAutoDocIndex.c to inform it of
that new sub-directory, add it to the string array autodocdir and
increase DIRCOUNT by one. If the supplied autodoc file isn't the
correct format, you may have to edit it a bit. In particular, each
entry should be separated by a form feed, and there should be exactly
one form feed before the first entry. Make sure that whatever is
ahead of the first entry has no form feeds. The name of each function
should appear on the line after the form feed. There may be no spaces
or tabs before the name (spaced or tabs after the name are ok). The
name may be preceded by some other names (such as the library name)
with slashes between, for example
intuition.library/OpenScreen
is acceptable.
MakeAutoDocIndex tries to catch and report any problems it might find.
With the 1.3 autodocs there are no problems.
MakeAutoDocIndex (like MakeHeaderIndex below) requires that the DOS
command 'sort' be in the C: directory or the current directory.
4.4 MakeHeaderIndex
MakeHeaderIndex is a program that builds index files from the include
files, so that LookUpHeader.ced may work efficiently. It assumes that
the includes are the ones from the 1.3 Native Developer's Kit,
available from Commodore. You must assign the label "ch:" to the
directory containing your compiler headers. MakeHeaderIndex scans the
eight subdirectories in "ch:" that it knows of - devices, exec,
graphics, hardware, intuition, libraries, resources, and workbench
(See MakeHeaderIndex.c).
MakeHeaderIndex will create a bunch of files in a subdirectory called
"Index" that it creates in the "ch:" directory. These files are
called IndexA, IndexB, etc. Each file contains all the functions that
start with that letter. The format will be:
structure; headerfile; line
or
define; headerfile; line
where structure or define is the name of the Amiga system structure
(eg. NewScreen) or #define'd value (eg. WBENCHSCREEN), headerfile is
the full name of the compiler header file (eg. ch:intuition/screens.h)
and line is the line number in the compiler header file where this
reference lies (eg. 95).
MakeHeaderIndex will locate all #define'd constants that have a
#define
at the very beginning of the line, as well as all structures that
begin with a
struct
at the very beginning of the line. This seems to be true for the
Amiga compiler headers.
If you have any headers that come with a sharable library, you must
place them in a sub-directory of the "ch:" directory. You must modify
MakeHeaderIndex.c to inform it of that new sub-directory (add it to
the string array includedir and increase DIRCOUNT by one). You must
also hope that all the #define's and struct's are at the extreme left
of their lines.
MakeHeaderIndex tries to catch and report any problems it might find.
With the 1.3 include files, there are no problems.
4.5 GenTags
GenTags is a C-language program that will scan a C-language source
file and generate a tag entry for each function defined in that file.
It takes as a single parameter the name of the source file:
GenTags foo.c
Each tag entry is of the following form:
function; file; line
where function is the name of the function that GenTags found, file is
the name of the file it was found in, and line is the line number
within that file where the function was defined. The tags are sent to
the standard output, so you will probably want to redirect them
somewhere. Usually, you will use the shell script MakeTags, which
calls GenTags for each file that matches a specified pattern, and
redirects the output to a file called tags.
GenTags is smarter than for example the program that generates tag
files for the editor vi. The only non-pathological case known for
which GenTags messes up is when there is an open comment ('/*') within
quotation marks. Except for that case, it should successfully find
all the functions (it performed flawlessly on 500K of source files
that comprise one project). Perhaps I left that one problem in so
that I have something to do for the next release...
Since the tag file contains the line number where a certain function
was defined, if you modify a source module after you've generated the
tags for it, then LookUpTag.ced may miss by a bit if you've added or
removed lines ahead of the function in question. As well, any
functions you've added to the source since you last generated the
tag files will of course not be in them. You will periodically want
to remake the tag files, which fortunately is relatively quick and
painless (I can build tags for 500K of source in less than one minute,
but then I have access to a 68030 at work).
5.0 C Language Sources
The sources for the five executable programs in the c directory of the
DevKit are provided. They all compile under Aztec C, and contain
suitable "Auto:" commands to compile properly. As such, they serve as
examples of how to set up "Auto:" commands properly.
6.0 Conclusion
Thanks to Bill Hawes for technical assistance, and to Mike Sinz for
encouranging me to make CommentBlock and UncommentBlock nest properly.
The ARexx and C language programs that comprise the DevKit make
developing on the Amiga much easier. They also serve as good examples
of ARexx programming. If you have any comments, suggestions, or
modifications, please bring them to my attention at
Peter Cherna
5511 Westbourne Ave.,
Cote St. Luc, Quebec
Canada
H4V 2G9
7.0 Future Avenues
Someday someone (perhaps me) will modify the DevKit so that
Compile.ced and NextError.ced work with the Lattice compiler. As
Lattice's CodePRobe is ARexx compatible, LookUp and LookUpHeader
functions could be added to it, which would be useful. Compile.ced
and NextError.ced could also be rewritten for other compilers (eg.
Modula 2.)
One annoying problem I have with Aztec is that compiler warnings
aren't included in the AztecC.err file; they always go to the standard
output. Aztec flags as warnings several things that I consider
errors, such as referencing foo->bar, where bar is not a field of the
structure foo, but is of some other structure. I'd like to write a
program that would take the redirected output of Aztec's cc, and
format warning messages and stuff them into AztecC.err along with the
errors.
As well, the ARexx programs might one day be rewritten to work with
other ARexx compatible editors.
If anybody succeeds in any of these areas, I would be delighted to
hear about it. As a suggestion, if you intend to rework Compile.ced
and NextError.ced to work with Lattice C, I would suggest you use some
other keyword than "Auto:", say "LAuto:", so that source code that
compiles under both Lattice and Aztec could have both "Auto:" and
"LAuto:" commands in it, and would compile depending on which version
of Compile.ced you used.